



<!doctype html>
<html lang="en" class="no-js">
  <head>
    
      <meta charset="utf-8">
      <meta name="viewport" content="width=device-width,initial-scale=1">
      <meta http-equiv="x-ua-compatible" content="ie=edge">
      
        <meta name="description" content="Deep learning toolbox">
      
      
        <link rel="canonical" href="https://uber.github.io/ludwig/api/">
      
      
        <meta name="author" content="Piero Molino">
      
      
        <meta name="lang:clipboard.copy" content="Copy to clipboard">
      
        <meta name="lang:clipboard.copied" content="Copied to clipboard">
      
        <meta name="lang:search.language" content="en">
      
        <meta name="lang:search.pipeline.stopwords" content="True">
      
        <meta name="lang:search.pipeline.trimmer" content="True">
      
        <meta name="lang:search.result.none" content="No matching documents">
      
        <meta name="lang:search.result.one" content="1 matching document">
      
        <meta name="lang:search.result.other" content="# matching documents">
      
        <meta name="lang:search.tokenizer" content="[\s\-]+">
      
      <link rel="shortcut icon" href="../images/ludwig_logo.png">
      <meta content="mkdocs-1.0.4, mkdocs-material-3.3.0" name="generator">
    
    
      
        <title>API - Ludwig</title>
      
    
    
      <link rel="stylesheet" href="../assets/stylesheets/application.572ca0f0.css">
      
        <link rel="stylesheet" href="../assets/stylesheets/application-palette.22915126.css">
      
      
        
        
        <meta name="theme-color" content="#757575">


      <script src="../assets/javascripts/modernizr.962652e9.js"></script>
    
    
      
        <link href="https://fonts.gstatic.com" rel="preconnect" crossorigin>
        <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,400,400i,700|Roboto+Mono">
        <style>body,input{font-family:"Roboto","Helvetica Neue",Helvetica,Arial,sans-serif}code,kbd,pre{font-family:"Roboto Mono","Courier New",Courier,monospace}</style>
      
    
    <link rel="stylesheet" href="../assets/fonts/material-icons.css">
    
    
      <link rel="stylesheet" href="../stylesheets/extra.css">
    
      <link rel="stylesheet" href="../stylesheets/monokai.css">


  </head>
  
    
    
    <body dir="ltr" data-md-color-primary="grey" data-md-color-accent="grey">
  
    <svg class="md-svg">
      <defs>
        
        
          <svg xmlns="http://www.w3.org/2000/svg" width="416" height="448"
    viewBox="0 0 416 448" id="__github">
  <path fill="currentColor" d="M160 304q0 10-3.125 20.5t-10.75 19-18.125
        8.5-18.125-8.5-10.75-19-3.125-20.5 3.125-20.5 10.75-19 18.125-8.5
        18.125 8.5 10.75 19 3.125 20.5zM320 304q0 10-3.125 20.5t-10.75
        19-18.125 8.5-18.125-8.5-10.75-19-3.125-20.5 3.125-20.5 10.75-19
        18.125-8.5 18.125 8.5 10.75 19 3.125 20.5zM360
        304q0-30-17.25-51t-46.75-21q-10.25 0-48.75 5.25-17.75 2.75-39.25
        2.75t-39.25-2.75q-38-5.25-48.75-5.25-29.5 0-46.75 21t-17.25 51q0 22 8
        38.375t20.25 25.75 30.5 15 35 7.375 37.25 1.75h42q20.5 0
        37.25-1.75t35-7.375 30.5-15 20.25-25.75 8-38.375zM416 260q0 51.75-15.25
        82.75-9.5 19.25-26.375 33.25t-35.25 21.5-42.5 11.875-42.875 5.5-41.75
        1.125q-19.5 0-35.5-0.75t-36.875-3.125-38.125-7.5-34.25-12.875-30.25-20.25-21.5-28.75q-15.5-30.75-15.5-82.75
        0-59.25 34-99-6.75-20.5-6.75-42.5 0-29 12.75-54.5 27 0 47.5 9.875t47.25
        30.875q36.75-8.75 77.25-8.75 37 0 70 8 26.25-20.5
        46.75-30.25t47.25-9.75q12.75 25.5 12.75 54.5 0 21.75-6.75 42 34 40 34
        99.5z" />
</svg>
        
      </defs>
    </svg>
    <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
    <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
    <label class="md-overlay" data-md-component="overlay" for="__drawer"></label>
    
      <a href="#ludwigmodel-class" tabindex="1" class="md-skip">
        Skip to content
      </a>
    
    
      <header class="md-header" data-md-component="header">
    <nav class="md-header-nav md-grid">
        <div class="md-flex">
            <div class="md-flex__cell md-flex__cell--shrink">
                <a class="md-header-nav__button md-logo"
                   href="https://uber.github.io/ludwig/" title="Ludwig">
                    <img src="../images/ludwig_logo.svg" style="height:2rem;">
                </a>
            </div>
            <div class="md-flex__cell md-flex__cell--shrink">
                <label class="md-icon md-icon--menu md-header-nav__button" for="__drawer"></label>
            </div>
            <div class="md-flex__cell md-flex__cell--stretch">
                <div class="md-flex__ellipsis md-header-nav__title" data-md-component="title">
                    
                    <span class="md-header-nav__topic">
                    API
                    </span>
                    
                </div>
            </div>
            <div class="md-flex__cell md-flex__cell--shrink">
                
                
                <label class="md-icon md-icon--search md-header-nav__button" for="__search"></label>
                
<div class="md-search" data-md-component="search" role="dialog">
  <label class="md-search__overlay" for="__search"></label>
  <div class="md-search__inner" role="search">
    <form class="md-search__form" name="search">
      <input type="text" class="md-search__input" name="query" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="query" data-md-state="active">
      <label class="md-icon md-search__icon" for="__search"></label>
      <button type="reset" class="md-icon md-search__icon" data-md-component="reset" tabindex="-1">
        &#xE5CD;
      </button>
    </form>
    <div class="md-search__output">
      <div class="md-search__scrollwrap" data-md-scrollfix>
        <div class="md-search-result" data-md-component="result">
          <div class="md-search-result__meta">
            Type to start searching
          </div>
          <ol class="md-search-result__list"></ol>
        </div>
      </div>
    </div>
  </div>
</div>
                
                
            </div>
            
            <div class="md-flex__cell md-flex__cell--shrink">
                <div class="md-header-nav__source">
                    


  


  <a href="https://github.com/uber/ludwig/" title="Go to repository" class="md-source" data-md-source="github">
    
      <div class="md-source__icon">
        <svg viewBox="0 0 24 24" width="24" height="24">
          <use xlink:href="#__github" width="24" height="24"></use>
        </svg>
      </div>
    
    <div class="md-source__repository">
      uber/ludwig
    </div>
  </a>

                </div>
            </div>
            
        </div>
    </nav>
</header>
    
    <div class="md-container">
      
        
      
      
      <main class="md-main">
        <div class="md-main__inner md-grid" data-md-component="container">
          
            
              <div class="md-sidebar md-sidebar--primary" data-md-component="navigation">
                <div class="md-sidebar__scrollwrap">
                  <div class="md-sidebar__inner">
                    <nav class="md-nav md-nav--primary" data-md-level="0">
    <label class="md-nav__title md-nav__title--site" for="__drawer">
        <a class="md-nav__button md-logo" href="https://uber.github.io/ludwig/"
           title="Ludwig">
            <img src="../images/ludwig_logo.svg" style="width: 20.8rem">
        </a>
    </label>
    
    <div class="md-nav__source">
        


  


  <a href="https://github.com/uber/ludwig/" title="Go to repository" class="md-source" data-md-source="github">
    
      <div class="md-source__icon">
        <svg viewBox="0 0 24 24" width="24" height="24">
          <use xlink:href="#__github" width="24" height="24"></use>
        </svg>
      </div>
    
    <div class="md-source__repository">
      uber/ludwig
    </div>
  </a>

    </div>
    
    <ul class="md-nav__list" data-md-scrollfix>
        
        
        
        


  <li class="md-nav__item">
    <a href=".." title="About" class="md-nav__link">
      About
    </a>
  </li>

        
        
        
        


  <li class="md-nav__item">
    <a href="../getting_started/" title="Getting Started" class="md-nav__link">
      Getting Started
    </a>
  </li>

        
        
        
        


  <li class="md-nav__item">
    <a href="../examples/" title="Examples" class="md-nav__link">
      Examples
    </a>
  </li>

        
        
        
        


  <li class="md-nav__item">
    <a href="../user_guide/" title="User Guide" class="md-nav__link">
      User Guide
    </a>
  </li>

        
        
        
        


  <li class="md-nav__item">
    <a href="../developer_guide/" title="Developer Guide" class="md-nav__link">
      Developer Guide
    </a>
  </li>

        
        
        
        

  


  <li class="md-nav__item md-nav__item--active">
    
    <input class="md-toggle md-nav__toggle" data-md-toggle="toc" type="checkbox" id="__toc">
    
    
      <label class="md-nav__link md-nav__link--active" for="__toc">
        API
      </label>
    
    <a href="./" title="API" class="md-nav__link md-nav__link--active">
      API
    </a>
    
      
<nav class="md-nav md-nav--secondary">
  
  
  
    <label class="md-nav__title" for="__toc">Table of contents</label>
    <ul class="md-nav__list" data-md-scrollfix>
      
        <li class="md-nav__item">
  <a href="#ludwigmodel-class" title="LudwigModel class" class="md-nav__link">
    LudwigModel class
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ludwigmodel-methods" title="LudwigModel methods" class="md-nav__link">
    LudwigModel methods
  </a>
  
    <nav class="md-nav">
      <ul class="md-nav__list">
        
          <li class="md-nav__item">
  <a href="#close" title="close" class="md-nav__link">
    close
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#initialize_model" title="initialize_model" class="md-nav__link">
    initialize_model
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#load" title="load" class="md-nav__link">
    load
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#predict" title="predict" class="md-nav__link">
    predict
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#save" title="save" class="md-nav__link">
    save
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#test" title="test" class="md-nav__link">
    test
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#train" title="train" class="md-nav__link">
    train
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#train_online" title="train_online" class="md-nav__link">
    train_online
  </a>
  
</li>
        
      </ul>
    </nav>
  
</li>
      
      
      
      
      
    </ul>
  
</nav>
    
  </li>

        
        
        
        


  <li class="md-nav__item">
    <a href="../faq/" title="FAQ" class="md-nav__link">
      FAQ
    </a>
  </li>

        
    </ul>
</nav>
                  </div>
                </div>
              </div>
            
            
              <div class="md-sidebar md-sidebar--secondary" data-md-component="toc">
                <div class="md-sidebar__scrollwrap">
                  <div class="md-sidebar__inner">
                    
<nav class="md-nav md-nav--secondary">
  
  
  
    <label class="md-nav__title" for="__toc">Table of contents</label>
    <ul class="md-nav__list" data-md-scrollfix>
      
        <li class="md-nav__item">
  <a href="#ludwigmodel-class" title="LudwigModel class" class="md-nav__link">
    LudwigModel class
  </a>
  
</li>
      
        <li class="md-nav__item">
  <a href="#ludwigmodel-methods" title="LudwigModel methods" class="md-nav__link">
    LudwigModel methods
  </a>
  
    <nav class="md-nav">
      <ul class="md-nav__list">
        
          <li class="md-nav__item">
  <a href="#close" title="close" class="md-nav__link">
    close
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#initialize_model" title="initialize_model" class="md-nav__link">
    initialize_model
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#load" title="load" class="md-nav__link">
    load
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#predict" title="predict" class="md-nav__link">
    predict
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#save" title="save" class="md-nav__link">
    save
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#test" title="test" class="md-nav__link">
    test
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#train" title="train" class="md-nav__link">
    train
  </a>
  
</li>
        
          <li class="md-nav__item">
  <a href="#train_online" title="train_online" class="md-nav__link">
    train_online
  </a>
  
</li>
        
      </ul>
    </nav>
  
</li>
      
      
      
      
      
    </ul>
  
</nav>
                  </div>
                </div>
              </div>
            
          
          <div class="md-content">
            <article class="md-content__inner md-typeset">
              
                
                  <a href="https://github.com/uber/ludwig/edit/master/docs/api.md" title="Edit this page" class="md-icon md-content__icon">&#xE3C9;</a>
                
                
                  <h1>API</h1>
                
                <p><span style="float:right;"><a href="https://github.com/uber/ludwig/blob/master/ludwig.py#L64">[source]</a></span></p>
<h2 id="ludwigmodel-class">LudwigModel class<a class="headerlink" href="#ludwigmodel-class" title="Permanent link">&para;</a></h2>
<div class="codehilite"><pre><span></span><span class="n">ludwig</span><span class="o">.</span><span class="n">LudwigModel</span><span class="p">(</span>
  <span class="n">model_definition</span><span class="p">,</span>
  <span class="n">model_definition_file</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">logging_level</span><span class="o">=</span><span class="mi">40</span>
<span class="p">)</span>
</pre></div>


<p>Class that allows access to high level Ludwig functionalities.</p>
<p><strong>Inputs</strong></p>
<ul>
<li><strong>model_definition</strong> (dict): a dictionary containing information needed
   to build a model. Refer to the [User Guide]
   (http://ludwig.ai/user-guide/m#model-definition) for details.</li>
<li><strong>model_definition_file</strong> (string, optional, default: <code>Mone</code>): path to
   a YAML file containing the model definition. If available it will be
   used instead of the model_definition dict.</li>
<li><strong>logging_level</strong> (int, default: <code>logging.ERROR</code>): logging level to use
   for logging. Use logging constants like <code>logging.DEBUG</code>,
   <code>logging.INFO</code> and <code>logging.ERROR</code>. By default only errors will be
   printed.</li>
</ul>
<p><strong>Example usage:</strong></p>
<div class="codehilite"><pre><span></span><span class="kn">from</span> <span class="nn">ludwig</span> <span class="kn">import</span> <span class="n">LudwigModel</span>
</pre></div>


<p>Train a model:</p>
<div class="codehilite"><pre><span></span><span class="n">model_definition</span> <span class="o">=</span> <span class="p">{</span><span class="o">...</span><span class="p">}</span>
<span class="n">ludwig_model</span> <span class="o">=</span> <span class="n">LudwigModel</span><span class="p">(</span><span class="n">model_definition</span><span class="p">)</span>
<span class="n">train_stats</span> <span class="o">=</span> <span class="n">ludwig_model</span><span class="o">.</span><span class="n">train</span><span class="p">(</span><span class="n">data_csv</span><span class="o">=</span><span class="n">csv_file_path</span><span class="p">)</span>
</pre></div>


<p>or</p>
<div class="codehilite"><pre><span></span><span class="n">train_stats</span> <span class="o">=</span> <span class="n">ludwig_model</span><span class="o">.</span><span class="n">train</span><span class="p">(</span><span class="n">data_df</span><span class="o">=</span><span class="n">dataframe</span><span class="p">)</span>
</pre></div>


<p>If you have already trained a model you cal load it and use it to predict</p>
<div class="codehilite"><pre><span></span><span class="n">ludwig_model</span> <span class="o">=</span> <span class="n">LudwigModel</span><span class="o">.</span><span class="n">load</span><span class="p">(</span><span class="n">model_dir</span><span class="p">)</span>
</pre></div>


<p>Predict:</p>
<div class="codehilite"><pre><span></span><span class="n">predictions</span> <span class="o">=</span> <span class="n">ludwig_model</span><span class="o">.</span><span class="n">predict</span><span class="p">(</span><span class="n">dataset_csv</span><span class="o">=</span><span class="n">csv_file_path</span><span class="p">)</span>
</pre></div>


<p>or</p>
<div class="codehilite"><pre><span></span><span class="n">predictions</span> <span class="o">=</span> <span class="n">ludwig_model</span><span class="o">.</span><span class="n">predict</span><span class="p">(</span><span class="n">dataset_df</span><span class="o">=</span><span class="n">dataframe</span><span class="p">)</span>
</pre></div>


<p>Finally in order to release resources:</p>
<div class="codehilite"><pre><span></span><span class="n">model</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
</pre></div>


<hr />
<h2 id="ludwigmodel-methods">LudwigModel methods<a class="headerlink" href="#ludwigmodel-methods" title="Permanent link">&para;</a></h2>
<h3 id="close">close<a class="headerlink" href="#close" title="Permanent link">&para;</a></h3>
<div class="codehilite"><pre><span></span><span class="n">close</span><span class="p">(</span>
<span class="p">)</span>
</pre></div>


<p>Closes an open LudwigModel (closing the session running it).
It should be called once done with the model to release resources.</p>
<hr />
<h3 id="initialize_model">initialize_model<a class="headerlink" href="#initialize_model" title="Permanent link">&para;</a></h3>
<div class="codehilite"><pre><span></span><span class="n">initialize_model</span><span class="p">(</span>
  <span class="n">train_set_metadata</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">train_set_metadata_json</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">gpus</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">gpu_fraction</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span>
  <span class="n">random_seed</span><span class="o">=</span><span class="mi">42</span><span class="p">,</span>
  <span class="n">logging_level</span><span class="o">=</span><span class="mi">40</span><span class="p">,</span>
  <span class="n">debug</span><span class="o">=</span><span class="bp">False</span>
<span class="p">)</span>
</pre></div>


<p>This function initializes a model. It is need for performing online
learning, so it has to be called before <code>train_online</code>.
<code>train</code> initialize the model under the hood, so there is no need to call
this function if you don't use <code>train_online</code>.</p>
<p><strong>Inputs</strong></p>
<ul>
<li><strong>train_set_metadata</strong> (dict): it contains metadata information for
   the input and output features the model is going to be trained
   on. It's the same content of the metadata json file that is
   created while training.</li>
<li><strong>train_set_metadata_json</strong> (string):  path to the JSON metadata file
   created while training. it contains metadata information for the
   input and output features the model is going to be trained on</li>
<li><strong>gpus</strong> (string, default: <code>None</code>): list of GPUs to use (it uses the
   same syntax of CUDA_VISIBLE_DEVICES)</li>
<li><strong>gpu_fraction</strong> (float, default <code>1.0</code>): fraction of GPU memory to
   initialize the process with</li>
<li><strong>random_seed</strong> (int, default<code>42</code>): a random seed that is going to be
   used anywhere there is a call to a random number generator: data
   splitting, parameter initialization and training set shuffling</li>
<li><strong>logging_level</strong> (int, default: <code>logging.ERROR</code>): logging level to
   use for logging. Use logging constants like <code>logging.DEBUG</code>,
   <code>logging.INFO</code> and <code>logging.ERROR</code>. By default only errors will
   be printed.</li>
<li><strong>debug</strong> (bool, default: <code>False</code>): enables debugging mode</li>
</ul>
<hr />
<h3 id="load">load<a class="headerlink" href="#load" title="Permanent link">&para;</a></h3>
<div class="codehilite"><pre><span></span><span class="n">load</span><span class="p">(</span>
  <span class="n">logging_level</span><span class="o">=</span><span class="mi">40</span>
<span class="p">)</span>
</pre></div>


<p>This function allows for loading pretrained models</p>
<p><strong>Inputs</strong></p>
<ul>
<li><strong>model_dir</strong> (string): path to the directory containing the model.
   If the model was trained by the <code>train</code> or <code>experiment</code> command,
   the model is in <code>results_dir/experiment_dir/model</code>.</li>
<li><strong>logging_level</strong> (int, default: <code>logging.ERROR</code>): logging level to
   use for logging. Use logging constants like <code>logging.DEBUG</code>,
   <code>logging.INFO</code> and <code>logging.ERROR</code>. By default only errors will
   be printed.</li>
</ul>
<p><strong>Return</strong></p>
<ul>
<li><strong>return</strong> ( a LudwigModel obje): a LudwigModel object</li>
</ul>
<p><strong>Example usage</strong></p>
<div class="codehilite"><pre><span></span><span class="n">ludwig_model</span> <span class="o">=</span> <span class="n">LudwigModel</span><span class="o">.</span><span class="n">load</span><span class="p">(</span><span class="n">model_dir</span><span class="p">)</span>
</pre></div>


<hr />
<h3 id="predict">predict<a class="headerlink" href="#predict" title="Permanent link">&para;</a></h3>
<div class="codehilite"><pre><span></span><span class="n">predict</span><span class="p">(</span>
  <span class="n">data_df</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">data_csv</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">data_dict</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">return_type</span><span class="o">=&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">pandas</span><span class="o">.</span><span class="n">core</span><span class="o">.</span><span class="n">frame</span><span class="o">.</span><span class="n">DataFrame</span><span class="s1">&#39;&gt;,</span>
  <span class="n">batch_size</span><span class="o">=</span><span class="mi">128</span><span class="p">,</span>
  <span class="n">gpus</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">gpu_fraction</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span>
  <span class="n">logging_level</span><span class="o">=</span><span class="mi">40</span>
<span class="p">)</span>
</pre></div>


<p>This function is used to predict the output variables given the input
variables using the trained model.</p>
<p><strong>Inputs</strong></p>
<ul>
<li><strong>data_df</strong> (DataFrame): dataframe containing data. Only the input
   features defined in the model definition need to be present in
   the dataframe.</li>
<li><strong>data_csv</strong> (string): input data CSV file. Only the input features
   defined in the model definition need to be present in the CSV.</li>
<li><strong>data_dict</strong> (dict): input data dictionary. It is expected to
   contain one key for each field and the values have to be lists
   of the same length. Each index in the lists corresponds to one
   datapoint. Only the input features defined in the model
   definition need to be present in the dataframe. For example a
   data set consisting of two datapoints with a input text may be
   provided as the following dict <code>`{'text_field_name}: ['text of
   the first datapoint', text of the second datapoint']}</code>.</li>
<li><strong>return_type</strong> (strng or type, default: <code>DataFrame</code>):
   string describing the type of the returned prediction object.
   <code>'dataframe'</code>, <code>'df'</code> and <code>DataFrame</code> will return a pandas
   DataFrame , while <code>'dict'</code>, ''dictionary'<code>and</code>dict` will
   return a dictionary.</li>
<li><strong>batch_size</strong> (int, default: <code>128</code>): batch size</li>
<li><strong>gpus</strong> (string, default: <code>None</code>): list of GPUs to use (it uses the
   same syntax of CUDA_VISIBLE_DEVICES)</li>
<li><strong>gpu_fraction</strong> (float, default <code>1.0</code>): fraction of gpu memory to
   initialize the process with</li>
<li><strong>logging_level</strong> (int, default: <code>logging.ERROR</code>): logging level to
   use for logging. Use logging constants like <code>logging.DEBUG</code>,
   <code>logging.INFO</code> and <code>logging.ERROR</code>. By default only errors will
   be printed.</li>
</ul>
<p><strong>Return</strong></p>
<ul>
<li><strong>return</strong> (DataFrame or dict): a dataframe containing the predictions for
     each output feature and their probabilities (for types that
     return them) will be returned. For instance in a 3 way
     multiclass classification problem with a category field names
     <code>class</code> as output feature with possible values <code>one</code>, <code>two</code>
     and <code>three</code>, the dataframe will have as many rows as input
     datapoints and five columns: <code>class_predictions</code>,
     <code>class_UNK_probability</code>, <code>class_one_probability</code>,
     <code>class_two_probability</code>, <code>class_three_probability</code>. (The UNK
     class is always present in categorical features).
     If the <code>return_type</code> is a dictionary, the returned object be
     a dictionary contaning one entry for each output feature.
     Each entry is itself a dictionary containing aligned
     arrays of predictions and probabilities / scores.</li>
</ul>
<hr />
<h3 id="save">save<a class="headerlink" href="#save" title="Permanent link">&para;</a></h3>
<div class="codehilite"><pre><span></span><span class="n">save</span><span class="p">(</span>
  <span class="n">save_path</span>
<span class="p">)</span>
</pre></div>


<p>This function allows for loading pretrained models</p>
<p><strong>Inputs</strong></p>
<ul>
<li><strong> save_path</strong> (string): path to the directory where the model is
    going to be saved. Both a JSON file containing the model
    architecture hyperparameters and checkpoints files containing
    model weights will be saved.</li>
</ul>
<p><strong>Example usage</strong></p>
<div class="codehilite"><pre><span></span><span class="n">ludwig_model</span><span class="o">.</span><span class="n">save</span><span class="p">(</span><span class="n">save_path</span><span class="p">)</span>
</pre></div>


<hr />
<h3 id="test">test<a class="headerlink" href="#test" title="Permanent link">&para;</a></h3>
<div class="codehilite"><pre><span></span><span class="n">test</span><span class="p">(</span>
  <span class="n">data_df</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">data_csv</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">data_dict</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">return_type</span><span class="o">=&lt;</span><span class="k">class</span> <span class="err">&#39;</span><span class="nc">pandas</span><span class="o">.</span><span class="n">core</span><span class="o">.</span><span class="n">frame</span><span class="o">.</span><span class="n">DataFrame</span><span class="s1">&#39;&gt;,</span>
  <span class="n">batch_size</span><span class="o">=</span><span class="mi">128</span><span class="p">,</span>
  <span class="n">gpus</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">gpu_fraction</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span>
  <span class="n">logging_level</span><span class="o">=</span><span class="mi">40</span>
<span class="p">)</span>
</pre></div>


<p>This function is used to predict the output variables given the input
variables using the trained model and compute test statistics like
performance measures, confusion matrices and the like.</p>
<p><strong>Inputs</strong></p>
<ul>
<li><strong>data_df</strong> (DataFrame): dataframe containing data. Both input and
   output features defined in the model definition need to be
   present in the dataframe.</li>
<li><strong>data_csv</strong> (string): input data CSV file. Both input and output
   features defined in the model definition need to be present in
   the CSV.</li>
<li><strong>data_dict</strong> (dict): input data dictionary. It is expected to
   contain one key for each field and the values have to be lists
   of the same length. Each index in the lists corresponds to one
   datapoint. Both input and output features defined in the model
   definition need to be present in the dataframe. For example a
   data set consisting of two datapoints with a input text may be
   provided as the following dict <code>`{'text_field_name}: ['text of
   the first datapoint', text of the second datapoint']}</code>.</li>
<li><strong>return_type</strong> (strng or type, default: <code>DataFrame</code>):
   string describing the type of the returned prediction object.
   <code>'dataframe'</code>, <code>'df'</code> and <code>DataFrame</code> will return a pandas
   DataFrame , while <code>'dict'</code>, ''dictionary'<code>and</code>dict` will
   return a dictionary.</li>
<li><strong>batch_size</strong> (int, default: <code>128</code>): batch size</li>
<li><strong>gpus</strong> (string, default: <code>None</code>): list of GPUs to use (it uses the
   same syntax of CUDA_VISIBLE_DEVICES)</li>
<li><strong>gpu_fraction</strong> (float, default <code>1.0</code>): fraction of GPU memory to
   initialize the process with</li>
<li><strong>logging_level</strong> (int, default: <code>logging.ERROR</code>): logging level to
   use for logging. Use logging constants like <code>logging.DEBUG</code>,
   <code>logging.INFO</code> and <code>logging.ERROR</code>. By default only errors will
   be printed.</li>
</ul>
<p><strong>Return</strong></p>
<ul>
<li><strong>return</strong> (tuple((DataFrame or dict):, dict)) a tuple of a dataframe and a
     dictionary. The dataframe contains the predictions for each
     output feature and their probabilities (for types that return
     them) will be returned. For instance in a 3 way multiclass
     classification problem with a category field names <code>class</code> as
     output feature with possible values <code>one</code>, <code>two</code> and <code>three</code>,
     the dataframe will have as many rows as input datapoints and
     five columns: <code>class_predictions</code>, <code>class_UNK_probability</code>,
     <code>class_one_probability</code>, <code>class_two_probability</code>,
     <code>class_three_probability</code>. (The UNK class is always present in
     categorical features).
     If the <code>return_type</code> is a dictionary, the first object
     of the tuple will be a dictionary contaning one entry
     for each output feature.
     Each entry is itself a dictionary containing aligned
     arrays of predictions and probabilities / scores.
     The second object of the tuple is a dictionary that contains
     the test statistics, with each key being the name of an output
     feature and the values being dictionaries containing measures
     names and their values.</li>
</ul>
<hr />
<h3 id="train">train<a class="headerlink" href="#train" title="Permanent link">&para;</a></h3>
<div class="codehilite"><pre><span></span><span class="n">train</span><span class="p">(</span>
  <span class="n">data_df</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">data_train_df</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">data_validation_df</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">data_test_df</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">data_csv</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">data_train_csv</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">data_validation_csv</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">data_test_csv</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">data_hdf5</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">data_train_hdf5</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">data_validation_hdf5</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">data_test_hdf5</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">train_set_metadata_json</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">model_name</span><span class="o">=</span><span class="s1">&#39;run&#39;</span><span class="p">,</span>
  <span class="n">model_load_path</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">model_resume_path</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">skip_save_progress_weights</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span>
  <span class="n">dataset_type</span><span class="o">=</span><span class="s1">&#39;generic&#39;</span><span class="p">,</span>
  <span class="n">skip_save_processed_input</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span>
  <span class="n">output_directory</span><span class="o">=</span><span class="s1">&#39;results&#39;</span><span class="p">,</span>
  <span class="n">gpus</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">gpu_fraction</span><span class="o">=</span><span class="mf">1.0</span><span class="p">,</span>
  <span class="n">random_seed</span><span class="o">=</span><span class="mi">42</span><span class="p">,</span>
  <span class="n">logging_level</span><span class="o">=</span><span class="mi">40</span><span class="p">,</span>
  <span class="n">debug</span><span class="o">=</span><span class="bp">False</span>
<span class="p">)</span>
</pre></div>


<p>This function is used to perform a full training of the model on the 
specified dataset.</p>
<p><strong>Inputs</strong></p>
<ul>
<li><strong>data_df</strong> (DataFrame): dataframe containing data. If it has a split
   column, it will be used for splitting (0: train, 1: validation,
   2: test), otherwise the dataset will be randomly split</li>
<li><strong>data_train_df</strong> (DataFrame): dataframe containing training data</li>
<li><strong>data_validation_df</strong> (DataFrame): dataframe containing validation
   data</li>
<li><strong>data_test_df</strong> (DataFrame dataframe containing test dat):data_test_df: (DataFrame dataframe containing test data</li>
<li><strong>data_csv</strong> (string): input data CSV file. If it has a split column,
   it will be used for splitting (0: train, 1: validation, 2: test),
   otherwise the dataset will be randomly split</li>
<li><strong>data_train_csv</strong> (string): input train data CSV file</li>
<li><strong>data_validation_csv</strong> (string): input validation data CSV file</li>
<li><strong>data_test_csv</strong> (string): input test data CSV file</li>
<li><strong>data_hdf5</strong> (string): input data HDF5 file. It is an intermediate
   preprocess  version of the input CSV created the first time a CSV
   file is used in the same directory with the same name and a hdf5
   extension</li>
<li><strong>data_train_hdf5</strong> (string): input train data HDF5 file. It is an
   intermediate preprocess  version of the input CSV created the
   first time a CSV file is used in the same directory with the same
   name and a hdf5 extension</li>
<li><strong>data_validation_hdf5</strong> (string): input validation data HDF5 file.
   It is an intermediate preprocess version of the input CSV created
   the first time a CSV file is used in the same directory with the
   same name and a hdf5 extension</li>
<li><strong>data_test_hdf5</strong> (string): input test data HDF5 file. It is an
   intermediate preprocess  version of the input CSV created the
   first time a CSV file is used in the same directory with the same
   name and a hdf5 extension</li>
<li><strong>train_set_metadata_json</strong> (string): input metadata JSON file. It is an
   intermediate preprocess file containing the mappings of the input
   CSV created the first time a CSV file is used in the same
   directory with the same name and a json extension</li>
<li><strong>model_name</strong> (string): a name for the model, user for the save
   directory</li>
<li><strong>model_load_path</strong> (string): path of a pretrained model to load as
   initialization</li>
<li><strong>model_resume_path</strong> (string): path of a the model directory to
   resume training of</li>
<li><strong>skip_save_progress_weights</strong> (bool, default: <code>False</code>): doesn't save
   weights after each epoch. By default Ludwig saves weights after
   each epoch for enabling resuming of training, but if the model is
   really big that can be time consuming and will save twice as much
   space, use this parameter to skip it.</li>
<li><strong>dataset_type</strong> (string, default: <code>'default'</code>): determines the type
   of preprocessing will be applied to the data. Only <code>generic</code> is
   available at the moment</li>
<li><strong>skip_save_processed_input</strong> (bool, default: <code>False</code>): skips saving
   intermediate HDF5 and JSON files</li>
<li><strong>output_directory</strong> (string, default: <code>'results'</code>): directory that
   contains the results</li>
<li><strong>gpus</strong> (string, default: <code>None</code>): list of GPUs to use (it uses the
   same syntax of CUDA_VISIBLE_DEVICES)</li>
<li><strong>gpu_fraction</strong> (float, default <code>1.0</code>): fraction of gpu memory to
   initialize the process with</li>
<li><strong>random_seed</strong> (int, default<code>42</code>): a random seed that is going to be
   used anywhere there is a call to a random number generator: data
   splitting, parameter initialization and training set shuffling</li>
<li><strong>debug</strong> (bool, default: <code>False</code>): enables debugging mode</li>
<li><strong>logging_level</strong> (int, default: <code>logging.ERROR</code>): logging level to
   use for logging. Use logging constants like <code>logging.DEBUG</code>,
   <code>logging.INFO</code> and <code>logging.ERROR</code>. By default only errors will
   be printed.</li>
</ul>
<p>There are three ways to provide data: by dataframes using the <code>_df</code>
parameters, by CSV using the <code>_csv</code> parameters and by HDF5 and JSON,
using <code>_hdf5</code> and <code>_json</code> parameters.
The DataFrame approach uses data previously obtained and put in a
dataframe, the CSV approach loads data from a CSV file, while HDF5 and
JSON load previously preprocessed HDF5 and JSON files (they are saved in
the same directory of the CSV they are obtained from).
For all three approaches either a full dataset can be provided (which
will be split randomly according to the split probabilities defined in
the model definition, by default 70% training, 10% validation and 20%
test) or, if it contanins a plit column, it will be plit according to
that column (interpreting 0 as training, 1 as validation and 2 as test).
Alternatively separated dataframes / CSV / HDF5 files can beprovided
for each split.</p>
<p>During training the model and statistics will be saved in a directory
<code>[output_dir]/[experiment_name]_[model_name]_n</code> where all variables are
resolved to user spiecified ones and <code>n</code> is an increasing number
starting from 0 used to differentiate different runs.</p>
<p><strong>Return</strong></p>
<ul>
<li><strong>return</strong> (dict): a dictionary containing training statistics for each
output feature containing loss and measures values for each epoch.</li>
</ul>
<hr />
<h3 id="train_online">train_online<a class="headerlink" href="#train_online" title="Permanent link">&para;</a></h3>
<div class="codehilite"><pre><span></span><span class="n">train_online</span><span class="p">(</span>
  <span class="n">data_df</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">data_csv</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">data_dict</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">batch_size</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">learning_rate</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">regularization_lambda</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">dropout_rate</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">bucketing_field</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">gpus</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
  <span class="n">gpu_fraction</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span>
  <span class="n">logging_level</span><span class="o">=</span><span class="mi">40</span>
<span class="p">)</span>
</pre></div>


<p>This function is used to perform one epoch of training of the model 
on the specified dataset.</p>
<p><strong>Inputs</strong></p>
<ul>
<li><strong>data_df</strong> (DataFrame): dataframe containing data.</li>
<li><strong>data_csv</strong> (string): input data CSV file.</li>
<li><strong>data_dict</strong> (dict): input data dictionary. It is expected to 
   contain one key for each field and the values have to be lists of 
   the same length. Each index in the lists corresponds to one 
   datapoint. For example a data set consisting of two datapoints 
   with a text and a class may be provided as the following dict 
   <code>`{'text_field_name}: ['text of the first datapoint', text of the 
   second datapoint'], 'class_filed_name': ['class_datapoints_1', 
   'class_datapoints_2']}</code>.</li>
<li><strong>batch_size</strong> (int): the batch size to use for training. By default 
   it's the one specified in the model definition.</li>
<li><strong>learning_rate</strong> (float): the learning rate to use for training. By
   default the values is the one specified in the model definition.</li>
<li><strong>regularization_lambda</strong> (float): the regularization lambda
   parameter to use for training. By default the values is the one
   specified in the model definition.</li>
<li><strong>dropout_rate</strong> (float): the dropout rate to use for training. By
   default the values is the one specified in the model definition.</li>
<li><strong>bucketing_field</strong> (string): the bucketing field to use for
   bucketing the data. By default the values is one specified in the
   model definition.</li>
<li><strong>gpus</strong> (string, default: <code>None</code>): list of GPUs to use (it uses the
   same syntax of CUDA_VISIBLE_DEVICES)</li>
<li><strong>gpu_fraction</strong> (float, default <code>1.0</code>): fraction of GPU memory to
   initialize the process with</li>
<li><strong>logging_level</strong> (int, default: <code>logging.ERROR</code>): logging level to
   use for logging. Use logging constants like <code>logging.DEBUG</code>,
   <code>logging.INFO</code> and <code>logging.ERROR</code>. By default only errors will
   be printed.</li>
</ul>
<p>There are three ways to provide data: by dataframes using the <code>data_df</code>
parameter, by CSV using the <code>data_csv</code> parameter and by dictionary,
using the <code>data_dict</code> parameter.</p>
<p>The DataFrame approach uses data previously obtained and put in a
dataframe, the CSV approach loads data from a CSV file, while dict
approach uses data organized by keys representing columns and values
that are lists of the datapoints for each. For example a data set
consisting of two datapoints with a text and a class may be provided as
the following dict <code>`{'text_field_name}: ['text of the first datapoint',
text of the second datapoint'], 'class_filed_name':
['class_datapoints_1', 'class_datapoints_2']}</code>.</p>
                
                  
                
              
              
                


              
            </article>
          </div>
        </div>
      </main>
      
        

<!-- Application footer -->
<footer class="md-footer">

    <!-- Link to previous and/or next page -->
    
    <div class="md-footer-nav">
        <nav class="md-footer-nav__inner md-grid">

            <!-- Link to previous page -->
            
            <a class="md-flex md-footer-nav__link md-footer-nav__link--prev"
               href="../developer_guide/"
               rel="prev"
               title="Developer Guide">
                <div class="md-flex__cell md-flex__cell--shrink">
                    <i class="md-icon md-icon--arrow-back
                    md-footer-nav__button"></i>
                </div>
                <div class="md-flex__cell md-flex__cell--stretch
                  md-footer-nav__title">
              <span class="md-flex__ellipsis">
                <span class="md-footer-nav__direction">
                  Previous
                </span>
                Developer Guide
              </span>
                </div>
            </a>
            

            <!-- Link to next page -->
            
            <a class="md-flex md-footer-nav__link md-footer-nav__link--next"
               href="../faq/"
               rel="next"
               title="FAQ">
                <div class="md-flex__cell md-flex__cell--stretch
                  md-footer-nav__title">
              <span class="md-flex__ellipsis">
                <span class="md-footer-nav__direction">
                  Next
                </span>
                FAQ
              </span>
                </div>
                <div class="md-flex__cell md-flex__cell--shrink">
                    <i class="md-icon md-icon--arrow-forward
                    md-footer-nav__button"></i>
                </div>
            </a>
            
        </nav>
    </div>
    

    <!-- Further information -->
    <div class="md-footer-meta md-typeset">
        <div class="md-footer-meta__inner md-grid">

            <!-- Copyright and theme information -->
            <div class="md-footer-copyright">
                <div class="footer-logo-smallpad"></div>
                
                <div class="md-footer-copyright__highlight">
                    Copyright &copy; 2018 - 2019 Uber Technologies Inc.
                </div>
                
                Website by <a href="http://w4nderlu.st">w4nderlust</a> powered by
                <a href="https://www.mkdocs.org">MkDocs</a>,
                <a href="https://squidfunk.github.io/mkdocs-material/">Material for MkDocs</a>,
                <a href="http://www.styleshout.com/">styleshout</a> and
                <a href="http://cables.gl/">cables</a>.
            </div>

            <!-- Social links -->
            
            
            
        </div>
    </div>
</footer>
      
    </div>

    <script src="../assets/javascripts/application.a353778b.js"></script>
      
      <script>app.initialize({version:"1.0.4",url:{base:".."}})</script>


    </body>
</html>